<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>string manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> string</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="string.htm#M2" NAME="L1778">NAME</A>
<DL><DD>string &mdash; Manipulate strings</DD></DL>
<DD><A HREF="string.htm#M3" NAME="L1779">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="string.htm#M4" NAME="L1780">DESCRIPTION</A>
<DL class="description">
<DD><A HREF="string.htm#M5" NAME="L1781"><B>string cat</B> ?<I>string1</I>? ?<I>string2...</I>?</A>
<DD><A HREF="string.htm#M6" NAME="L1782"><B>string compare</B> ?<B>-nocase</B>? ?<B>-length</B><I> length</I>? <I>string1 string2</I></A>
<DD><A HREF="string.htm#M7" NAME="L1783"><B>string equal</B> ?<B>-nocase</B>? ?<B>-length</B><I> length</I>? <I>string1 string2</I></A>
<DD><A HREF="string.htm#M8" NAME="L1784"><B>string first </B><I>needleString haystackString</I> ?<I>startIndex</I>?</A>
<DD><A HREF="string.htm#M9" NAME="L1785"><B>string index </B><I>string charIndex</I></A>
<DD><A HREF="string.htm#M10" NAME="L1786"><B>string is </B><I>class</I> ?<B>-strict</B>? ?<B>-failindex </B><I>varname</I>? <I>string</I></A>
<DL class="description">
<DD><A HREF="string.htm#M11" NAME="L1787"><B>alnum</B></A>
<DD><A HREF="string.htm#M12" NAME="L1788"><B>alpha</B></A>
<DD><A HREF="string.htm#M13" NAME="L1789"><B>ascii</B></A>
<DD><A HREF="string.htm#M14" NAME="L1790"><B>boolean</B></A>
<DD><A HREF="string.htm#M15" NAME="L1791"><B>control</B></A>
<DD><A HREF="string.htm#M16" NAME="L1792"><B>digit</B></A>
<DD><A HREF="string.htm#M17" NAME="L1793"><B>double</B></A>
<DD><A HREF="string.htm#M18" NAME="L1794"><B>entier</B></A>
<DD><A HREF="string.htm#M19" NAME="L1795"><B>false</B></A>
<DD><A HREF="string.htm#M20" NAME="L1796"><B>graph</B></A>
<DD><A HREF="string.htm#M21" NAME="L1797"><B>integer</B></A>
<DD><A HREF="string.htm#M22" NAME="L1798"><B>list</B></A>
<DD><A HREF="string.htm#M23" NAME="L1799"><B>lower</B></A>
<DD><A HREF="string.htm#M24" NAME="L1800"><B>print</B></A>
<DD><A HREF="string.htm#M25" NAME="L1801"><B>punct</B></A>
<DD><A HREF="string.htm#M26" NAME="L1802"><B>space</B></A>
<DD><A HREF="string.htm#M27" NAME="L1803"><B>true</B></A>
<DD><A HREF="string.htm#M28" NAME="L1804"><B>upper</B></A>
<DD><A HREF="string.htm#M29" NAME="L1805"><B>wideinteger</B></A>
<DD><A HREF="string.htm#M30" NAME="L1806"><B>wordchar</B></A>
<DD><A HREF="string.htm#M31" NAME="L1807"><B>xdigit</B></A>
</DL>
<DD><A HREF="string.htm#M32" NAME="L1808"><B>string last </B><I>needleString haystackString</I> ?<I>lastIndex</I>?</A>
<DD><A HREF="string.htm#M33" NAME="L1809"><B>string length </B><I>string</I></A>
<DD><A HREF="string.htm#M34" NAME="L1810"><B>string map</B> ?<B>-nocase</B>? <I>mapping string</I></A>
<DD><A HREF="string.htm#M35" NAME="L1811"><B>string match</B> ?<B>-nocase</B>? <I>pattern</I> <I>string</I></A>
<DL class="description">
<DD><A HREF="string.htm#M36" NAME="L1812"><B>*</B></A>
<DD><A HREF="string.htm#M37" NAME="L1813"><B>?</B></A>
<DD><A HREF="string.htm#M38" NAME="L1814"><B>[</B><I>chars</I><B>]</B></A>
<DD><A HREF="string.htm#M39" NAME="L1815"><B>&#92;</B><I>x</I></A>
</DL>
<DD><A HREF="string.htm#M40" NAME="L1816"><B>string range </B><I>string first last</I></A>
<DD><A HREF="string.htm#M41" NAME="L1817"><B>string repeat </B><I>string count</I></A>
<DD><A HREF="string.htm#M42" NAME="L1818"><B>string replace </B><I>string first last</I> ?<I>newstring</I>?</A>
<DD><A HREF="string.htm#M43" NAME="L1819"><B>string reverse </B><I>string</I></A>
<DD><A HREF="string.htm#M44" NAME="L1820"><B>string tolower </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
<DD><A HREF="string.htm#M45" NAME="L1821"><B>string totitle </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
<DD><A HREF="string.htm#M46" NAME="L1822"><B>string toupper </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A>
<DD><A HREF="string.htm#M47" NAME="L1823"><B>string trim </B><I>string</I> ?<I>chars</I>?</A>
<DD><A HREF="string.htm#M48" NAME="L1824"><B>string trimleft </B><I>string</I> ?<I>chars</I>?</A>
<DD><A HREF="string.htm#M49" NAME="L1825"><B>string trimright </B><I>string</I> ?<I>chars</I>?</A>
</DL>
<DD><A HREF="string.htm#M50" NAME="L1826">OBSOLETE SUBCOMMANDS</A>
<DL class="obsolete subcommands">
<DD><A HREF="string.htm#M51" NAME="L1827"><B>string bytelength </B><I>string</I></A>
<DD><A HREF="string.htm#M52" NAME="L1828"><B>string wordend </B><I>string charIndex</I></A>
<DD><A HREF="string.htm#M53" NAME="L1829"><B>string wordstart </B><I>string charIndex</I></A>
</DL>
<DD><A HREF="string.htm#M54" NAME="L1830">STRING INDICES</A>
<DL class="string indices">
<DD><A HREF="string.htm#M55" NAME="L1831"><I>integer</I></A>
<DD><A HREF="string.htm#M56" NAME="L1832"><B>end</B></A>
<DD><A HREF="string.htm#M57" NAME="L1833"><B>end-</B><I>N</I></A>
<DD><A HREF="string.htm#M58" NAME="L1834"><B>end+</B><I>N</I></A>
<DD><A HREF="string.htm#M59" NAME="L1835"><I>M</I><B>+</B><I>N</I></A>
<DD><A HREF="string.htm#M60" NAME="L1836"><I>M</I><B>-</B><I>N</I></A>
</DL>
<DD><A HREF="string.htm#M61" NAME="L1837">EXAMPLE</A>
<DD><A HREF="string.htm#M62" NAME="L1838">SEE ALSO</A>
<DD><A HREF="string.htm#M63" NAME="L1839">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
string &mdash; Manipulate strings
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>string </B><I>option arg </I>?<I>arg ...?</I><BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
Performs one of several string operations, depending on <I>option</I>.
The legal <I>option</I>s (which may be abbreviated) are:
<P>
<DL class="description">
<DT><A NAME="M5"><B>string cat</B> ?<I>string1</I>? ?<I>string2...</I>?</A><DD>
Concatenate the given <I>string</I>s just like placing them directly
next to each other and return the resulting compound string.  If no
<I>string</I>s are present, the result is an empty string.
<P>
This primitive is occasionally handier than juxtaposition of strings
when mixed quoting is wanted, or when the aim is to return the result
of a concatenation without resorting to <B><A HREF="../TclCmd/return.htm">return</A></B> <B>-level 0</B>,
and is more efficient than building a list of arguments and using
<B><A HREF="../TclCmd/join.htm">join</A></B> with an empty join string.
<P><DT><A NAME="M6"><B>string compare</B> ?<B>-nocase</B>? ?<B>-length</B><I> length</I>? <I>string1 string2</I></A><DD>
Perform a character-by-character comparison of strings <I>string1</I>
and <I>string2</I>.  Returns -1, 0, or 1, depending on whether
<I>string1</I> is lexicographically less than, equal to, or greater
than <I>string2</I>.  If <B>-length</B> is specified, then only the
first <I>length</I> characters are used in the comparison.  If
<B>-length</B> is negative, it is ignored.  If <B>-nocase</B> is
specified, then the strings are compared in a case-insensitive manner.
<P><DT><A NAME="M7"><B>string equal</B> ?<B>-nocase</B>? ?<B>-length</B><I> length</I>? <I>string1 string2</I></A><DD>
Perform a character-by-character comparison of strings <I>string1</I>
and <I>string2</I>.  Returns 1 if <I>string1</I> and <I>string2</I> are
identical, or 0 when not.  If <B>-length</B> is specified, then only
the first <I>length</I> characters are used in the comparison.  If
<B>-length</B> is negative, it is ignored.  If <B>-nocase</B> is
specified, then the strings are compared in a case-insensitive manner.
<P><DT><A NAME="M8"><B>string first </B><I>needleString haystackString</I> ?<I>startIndex</I>?</A><DD>
Search <I>haystackString</I> for a sequence of characters that exactly match
the characters in <I>needleString</I>.  If found, return the index of the
first character in the first such match within <I>haystackString</I>.  If not
found, return -1.  If <I>startIndex</I> is specified (in any of the
forms described in <B><A HREF="#M54">STRING INDICES</A></B>), then the search is
constrained to start with the character in <I>haystackString</I> specified by
the index.  For example,
<P>
<PRE><B>string first a 0a23456789abcdef 5</B></PRE>
<P>
will return <B>10</B>, but
<P>
<PRE><B>string first a 0123456789abcdef 11</B></PRE>
<P>will return <B>-1</B>.
<P><DT><A NAME="M9"><B>string index </B><I>string charIndex</I></A><DD>
Returns the <I>charIndex</I>'th character of the <I>string</I> argument.
A <I>charIndex</I> of 0 corresponds to the first character of the
string.  <I>charIndex</I> may be specified as described in the
<B><A HREF="#M54">STRING INDICES</A></B> section.
<P>
If <I>charIndex</I> is less than 0 or greater than or equal to the
length of the string then this command returns an empty string.
<P><DT><A NAME="M10"><B>string is </B><I>class</I> ?<B>-strict</B>? ?<B>-failindex </B><I>varname</I>? <I>string</I></A><DD>
Returns 1 if <I>string</I> is a valid member of the specified character
class, otherwise returns 0.  If <B>-strict</B> is specified, then an
empty string returns 0, otherwise an empty string will return 1 on
any class.  If <B>-failindex</B> is specified, then if the function
returns 0, the index in the string where the class was no longer valid
will be stored in the variable named <I>varname</I>.  The <I>varname</I>
will not be set if <B>string is</B> returns 1.  The following character
classes are recognized (the class name can be abbreviated):
<P>
<DL class="description">
<DT><A NAME="M11"><B>alnum</B></A><DD>
Any Unicode alphabet or digit character.
<P><DT><A NAME="M12"><B>alpha</B></A><DD>
Any Unicode alphabet character.
<P><DT><A NAME="M13"><B>ascii</B></A><DD>
Any character with a value less than &#92;u0080 (those that are in the
7-bit ascii range).
<P><DT><A NAME="M14"><B>boolean</B></A><DD>
Any of the forms allowed to <B><A HREF="../TclLib/GetInt.htm">Tcl_GetBoolean</A></B>.
<P><DT><A NAME="M15"><B>control</B></A><DD>
Any Unicode control character.
<P><DT><A NAME="M16"><B>digit</B></A><DD>
Any Unicode digit character.  Note that this includes characters
outside of the [0-9] range.
<P><DT><A NAME="M17"><B>double</B></A><DD>
Any of the forms allowed to <B><A HREF="../TclLib/DoubleObj.htm">Tcl_GetDoubleFromObj</A></B>.
<P><DT><A NAME="M18"><B>entier</B></A><DD>
Any of the valid string formats for an integer value of arbitrary size
in Tcl, with optional surrounding whitespace. The formats accepted are
exactly those accepted by the C routine <B><A HREF="../TclLib/IntObj.htm">Tcl_GetBignumFromObj</A></B>.
<P><DT><A NAME="M19"><B>false</B></A><DD>
Any of the forms allowed to <B><A HREF="../TclLib/GetInt.htm">Tcl_GetBoolean</A></B> where the value is
false.
<P><DT><A NAME="M20"><B>graph</B></A><DD>
Any Unicode printing character, except space.
<P><DT><A NAME="M21"><B>integer</B></A><DD>
Any of the valid string formats for a 32-bit integer value in Tcl,
with optional surrounding whitespace.  In case of overflow in
the value, 0 is returned and the <I>varname</I> will contain -1.
<P><DT><A NAME="M22"><B>list</B></A><DD>
Any proper list structure, with optional surrounding whitespace. In
case of improper list structure, 0 is returned and the <I>varname</I>
will contain the index of the
&ldquo;element&rdquo;
where the list parsing fails, or -1 if this cannot be determined.
<P><DT><A NAME="M23"><B>lower</B></A><DD>
Any Unicode lower case alphabet character.
<P><DT><A NAME="M24"><B>print</B></A><DD>
Any Unicode printing character, including space.
<P><DT><A NAME="M25"><B>punct</B></A><DD>
Any Unicode punctuation character.
<P><DT><A NAME="M26"><B>space</B></A><DD>
Any Unicode whitespace character, mongolian vowel separator
(U+180e), zero width space (U+200b), word joiner (U+2060) or
zero width no-break space (U+feff) (=BOM).
<P><DT><A NAME="M27"><B>true</B></A><DD>
Any of the forms allowed to <B><A HREF="../TclLib/GetInt.htm">Tcl_GetBoolean</A></B> where the value is
true.
<P><DT><A NAME="M28"><B>upper</B></A><DD>
Any upper case alphabet character in the Unicode character set.
<P><DT><A NAME="M29"><B>wideinteger</B></A><DD>
Any of the valid forms for a wide integer in Tcl, with optional
surrounding whitespace.  In case of overflow in the value, 0 is
returned and the <I>varname</I> will contain -1.
<P><DT><A NAME="M30"><B>wordchar</B></A><DD>
Any Unicode word character.  That is any alphanumeric character, and
any Unicode connector punctuation characters (e.g. underscore).
<P><DT><A NAME="M31"><B>xdigit</B></A><DD>
Any hexadecimal digit character ([0-9A-Fa-f]).
</DL><P>In the case of <B>boolean</B>, <B>true</B> and <B>false</B>, if the
function will return 0, then the <I>varname</I> will always be set to
0, due to the varied nature of a valid boolean value.<DL class="description">
</DL>
<P><DT><A NAME="M32"><B>string last </B><I>needleString haystackString</I> ?<I>lastIndex</I>?</A><DD>
Search <I>haystackString</I> for a sequence of characters that exactly match
the characters in <I>needleString</I>.  If found, return the index of the
first character in the last such match within <I>haystackString</I>.  If there
is no match, then return -1.  If <I>lastIndex</I> is specified (in any
of the forms described in <B><A HREF="#M54">STRING INDICES</A></B>), then only the
characters in <I>haystackString</I> at or before the specified <I>lastIndex</I>
will be considered by the search.  For example,
<P>
<PRE><B>string last a 0a23456789abcdef 15</B></PRE>
<P>
will return <B>10</B>, but
<P>
<PRE><B>string last a 0a23456789abcdef 9</B></PRE>
<P>will return <B>1</B>.
<P><DT><A NAME="M33"><B>string length </B><I>string</I></A><DD>
Returns a decimal string giving the number of characters in
<I>string</I>.  Note that this is not necessarily the same as the
number of bytes used to store the string.  If the value is a
byte array value (such as those returned from reading a binary encoded
channel), then this will return the actual byte length of the value.
<P><DT><A NAME="M34"><B>string map</B> ?<B>-nocase</B>? <I>mapping string</I></A><DD>
Replaces substrings in <I>string</I> based on the key-value pairs in
<I>mapping</I>.  <I>mapping</I> is a list of <I>key value key value ...</I>
as in the form returned by <B><A HREF="../TclCmd/array.htm">array get</A></B>.  Each instance of a
key in the string will be replaced with its corresponding value.  If
<B>-nocase</B> is specified, then matching is done without regard to
case differences. Both <I>key</I> and <I>value</I> may be multiple
characters.  Replacement is done in an ordered manner, so the key
appearing first in the list will be checked first, and so on.
<I>string</I> is only iterated over once, so earlier key replacements
will have no affect for later key matches.  For example,
<P>
<PRE><B>string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</B></PRE>
<P>
will return the string <B>01321221</B>.
<P>
Note that if an earlier <I>key</I> is a prefix of a later one, it will
completely mask the later one.  So if the previous example is
reordered like this,
<P>
<PRE><B>string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc</B></PRE>
<P>it will return the string <B>02c322c222c</B>.
<P><DT><A NAME="M35"><B>string match</B> ?<B>-nocase</B>? <I>pattern</I> <I>string</I></A><DD>
See if <I>pattern</I> matches <I>string</I>; return 1 if it does, 0 if
it does not.  If <B>-nocase</B> is specified, then the pattern attempts
to match against the string in a case insensitive manner.  For the two
strings to match, their contents must be identical except that the
following special sequences may appear in <I>pattern</I>:
<P>
<DL class="description">
<DT><A NAME="M36"><B>*</B></A><DD>
Matches any sequence of characters in <I>string</I>, including a null
string.
<P><DT><A NAME="M37"><B>?</B></A><DD>
Matches any single character in <I>string</I>.
<P><DT><A NAME="M38"><B>[</B><I>chars</I><B>]</B></A><DD>
Matches any character in the set given by <I>chars</I>.  If a sequence
of the form <I>x</I><B>-</B><I>y</I> appears in <I>chars</I>, then any
character between <I>x</I> and <I>y</I>, inclusive, will match.  When
used with <B>-nocase</B>, the end points of the range are converted to
lower case first.  Whereas {[A-z]} matches
&ldquo;_&rdquo;
when matching case-sensitively (since
&ldquo;_&rdquo;
falls between the
&ldquo;Z&rdquo;
and
&ldquo;a&rdquo;),
with <B>-nocase</B> this is considered like {[A-Za-z]} (and
probably what was meant in the first place).
<P><DT><A NAME="M39"><B>&#92;</B><I>x</I></A><DD>
Matches the single character <I>x</I>.  This provides a way of avoiding
the special interpretation of the characters <B>*?[]&#92;</B> in
<I>pattern</I>.
<P></DL>
<P><DT><A NAME="M40"><B>string range </B><I>string first last</I></A><DD>
Returns a range of consecutive characters from <I>string</I>, starting
with the character whose index is <I>first</I> and ending with the
character whose index is <I>last</I>. An index of 0 refers to the first
character of the string.  <I>first</I> and <I>last</I> may be specified
as for the <B>index</B> method.  If <I>first</I> is less than zero then
it is treated as if it were zero, and if <I>last</I> is greater than or
equal to the length of the string then it is treated as if it were
<B>end</B>.  If <I>first</I> is greater than <I>last</I> then an empty
string is returned.
<P><DT><A NAME="M41"><B>string repeat </B><I>string count</I></A><DD>
Returns <I>string</I> repeated <I>count</I> number of times.
<P><DT><A NAME="M42"><B>string replace </B><I>string first last</I> ?<I>newstring</I>?</A><DD>
Removes a range of consecutive characters from <I>string</I>, starting
with the character whose index is <I>first</I> and ending with the
character whose index is <I>last</I>.  An index of 0 refers to the
first character of the string.  <I>First</I> and <I>last</I> may be
specified as for the <B>index</B> method.  If <I>newstring</I> is
specified, then it is placed in the removed character range.  If
<I>first</I> is less than zero then it is treated as if it were zero,
and if <I>last</I> is greater than or equal to the length of the string
then it is treated as if it were <B>end</B>.  If <I>first</I> is greater
than <I>last</I> or the length of the initial string, or <I>last</I> is
less than 0, then the initial string is returned untouched.
<P><DT><A NAME="M43"><B>string reverse </B><I>string</I></A><DD>
Returns a string that is the same length as <I>string</I> but with its
characters in the reverse order.
<P><DT><A NAME="M44"><B>string tolower </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
Returns a value equal to <I>string</I> except that all upper (or title)
case letters have been converted to lower case.  If <I>first</I> is
specified, it refers to the first char index in the string to start
modifying.  If <I>last</I> is specified, it refers to the char index in
the string to stop at (inclusive).  <I>first</I> and <I>last</I> may be
specified using the forms described in <B><A HREF="#M54">STRING INDICES</A></B>.
<P><DT><A NAME="M45"><B>string totitle </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
Returns a value equal to <I>string</I> except that the first character
in <I>string</I> is converted to its Unicode title case variant (or
upper case if there is no title case variant) and the rest of the
string is converted to lower case.  If <I>first</I> is specified, it
refers to the first char index in the string to start modifying.  If
<I>last</I> is specified, it refers to the char index in the string to
stop at (inclusive).  <I>first</I> and <I>last</I> may be specified
using the forms described in <B><A HREF="#M54">STRING INDICES</A></B>.
<P><DT><A NAME="M46"><B>string toupper </B><I>string</I> ?<I>first</I>? ?<I>last</I>?</A><DD>
Returns a value equal to <I>string</I> except that all lower (or title)
case letters have been converted to upper case.  If <I>first</I> is
specified, it refers to the first char index in the string to start
modifying.  If <I>last</I> is specified, it refers to the char index in
the string to stop at (inclusive).  <I>first</I> and <I>last</I> may be
specified using the forms described in <B><A HREF="#M54">STRING INDICES</A></B>.
<P><DT><A NAME="M47"><B>string trim </B><I>string</I> ?<I>chars</I>?</A><DD>
Returns a value equal to <I>string</I> except that any leading or
trailing characters present in the string given by <I>chars</I> are removed.  If
<I>chars</I> is not specified then white space is removed (any character
for which <B>string is space</B> returns 1, and &quot;&#92;0&quot;).
<P><DT><A NAME="M48"><B>string trimleft </B><I>string</I> ?<I>chars</I>?</A><DD>
Returns a value equal to <I>string</I> except that any leading
characters present in the string given by <I>chars</I> are removed.  If
<I>chars</I> is not specified then white space is removed (any character
for which <B>string is space</B> returns 1, and &quot;&#92;0&quot;).
<P><DT><A NAME="M49"><B>string trimright </B><I>string</I> ?<I>chars</I>?</A><DD>
Returns a value equal to <I>string</I> except that any trailing
characters present in the string given by <I>chars</I> are removed.  If
<I>chars</I> is not specified then white space is removed (any character
for which <B>string is space</B> returns 1, and &quot;&#92;0&quot;).
<P></DL>
<H4><A NAME="M50">OBSOLETE SUBCOMMANDS</A></H4>
These subcommands are currently supported, but are likely to go away in a
future release as their functionality is either virtually never used or highly
misleading.
<P>
<DL class="obsolete subcommands">
<DT><A NAME="M51"><B>string bytelength </B><I>string</I></A><DD>
Returns a decimal string giving the number of bytes used to represent
<I>string</I> in memory when encoded as Tcl's internal modified UTF-8;
Tcl may use other encodings for <I>string</I> as well, and does not
guarantee to only use a single encoding for a particular <I>string</I>.
Because UTF-8 uses a variable number of bytes to represent Unicode
characters, the byte length will not be the same as the character
length in general.  The cases where a script cares about the byte
length are rare.
<P>
In almost all cases, you should use the
<B>string length</B> operation (including determining the length of a
Tcl byte array value).  Refer to the <B><A HREF="../TclLib/Utf.htm">Tcl_NumUtfChars</A></B> manual
entry for more details on the UTF-8 representation.
<P>
Formally, the <B>string bytelength</B> operation returns the content of
the <I>length</I> field of the <B><A HREF="../TclLib/Object.htm">Tcl_Obj</A></B> structure, after calling
<B><A HREF="../TclLib/StringObj.htm">Tcl_GetString</A></B> to ensure that the <I>bytes</I> field is populated.
This is highly unlikely to be useful to Tcl scripts, as Tcl's internal
encoding is not strict UTF-8, but rather a modified CESU-8 with a
denormalized NUL (identical to that used in a number of places by
Java's serialization mechanism) to enable basic processing with
non-Unicode-aware C functions.  As this representation should only
ever be used by Tcl's implementation, the number of bytes used to
store the representation is of very low value (except to C extension
code, which has direct access for the purpose of memory management,
etc.)
<P>
<I>Compatibility note:</I> it is likely that this subcommand will be
withdrawn in a future version of Tcl. It is better to use the
<B><A HREF="../TclCmd/encoding.htm">encoding convertto</A></B> command to convert a string to a known
encoding and then apply <B>string length</B> to that.
<P>
<PRE><B>string length</B> [encoding convertto utf-8 $theString]</PRE>
<P><DT><A NAME="M52"><B>string wordend </B><I>string charIndex</I></A><DD>
Returns the index of the character just after the last one in the word
containing character <I>charIndex</I> of <I>string</I>.  <I>charIndex</I>
may be specified using the forms in <B><A HREF="#M54">STRING INDICES</A></B>.  A word is
considered to be any contiguous range of alphanumeric (Unicode letters
or decimal digits) or underscore (Unicode connector punctuation)
characters, or any single character other than these.
<P><DT><A NAME="M53"><B>string wordstart </B><I>string charIndex</I></A><DD>
Returns the index of the first character in the word containing character
<I>charIndex</I> of <I>string</I>.  <I>charIndex</I> may be specified using the
forms in <B><A HREF="#M54">STRING INDICES</A></B>.  A word is considered to be any contiguous
range of alphanumeric (Unicode letters or decimal digits) or underscore
(Unicode connector punctuation) characters, or any single character other than
these.
<P></DL>
<H3><A NAME="M54">STRING INDICES</A></H3>
When referring to indices into a string (e.g., for <B>string index</B>
or <B>string range</B>) the following formats are supported:
<P>
<DL class="string indices">
<DT><A NAME="M55"><I>integer</I></A><DD>
For any index value that passes <B>string is integer -strict</B>,
the char specified at this integral index (e.g., <B>2</B> would refer to the
&ldquo;c&rdquo;
in
&ldquo;abcd&rdquo;).
<P><DT><A NAME="M56"><B>end</B></A><DD>
The last char of the string (e.g., <B>end</B> would refer to the
&ldquo;d&rdquo;
in
&ldquo;abcd&rdquo;).
<P><DT><A NAME="M57"><B>end-</B><I>N</I></A><DD>
The last char of the string minus the specified integer offset <I>N</I> (e.g.,
&ldquo;<B>end-1</B>&rdquo;
would refer to the
&ldquo;c&rdquo;
in
&ldquo;abcd&rdquo;).
<P><DT><A NAME="M58"><B>end+</B><I>N</I></A><DD>
The last char of the string plus the specified integer offset <I>N</I> (e.g.,
&ldquo;<B>end+-1</B>&rdquo;
would refer to the
&ldquo;c&rdquo;
in
&ldquo;abcd&rdquo;).
<P><DT><A NAME="M59"><I>M</I><B>+</B><I>N</I></A><DD>
The char specified at the integral index that is the sum of
integer values <I>M</I> and <I>N</I> (e.g.,
&ldquo;<B>1+1</B>&rdquo;
would refer to the
&ldquo;c&rdquo;
in
&ldquo;abcd&rdquo;).
<P><DT><A NAME="M60"><I>M</I><B>-</B><I>N</I></A><DD>
The char specified at the integral index that is the difference of
integer values <I>M</I> and <I>N</I> (e.g.,
&ldquo;<B>2-1</B>&rdquo;
would refer to the
&ldquo;b&rdquo;
in
&ldquo;abcd&rdquo;).
<P></DL>
<P>
In the specifications above, the integer value <I>M</I> contains no
trailing whitespace and the integer value <I>N</I> contains no
leading whitespace.
<H3><A NAME="M61">EXAMPLE</A></H3>
Test if the string in the variable <I>string</I> is a proper non-empty
prefix of the string <B>foobar</B>.
<P>
<PRE>set length [<B>string length</B> $string]
if {$length == 0} {
    set isPrefix 0
} else {
    set isPrefix [<B>string equal</B> -length $length $string &quot;foobar&quot;]
}</PRE>
<H3><A NAME="M62">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/expr.htm">expr</A></B>, <B><A HREF="../TclCmd/list.htm">list</A></B>
<H3><A NAME="M63">KEYWORDS</A></H3>
<A href="../Keywords/C.htm#case conversion">case conversion</A>, <A href="../Keywords/C.htm#compare">compare</A>, <A href="../Keywords/I.htm#index">index</A>, <A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/S.htm#string">string</A>, <A href="../Keywords/W.htm#word">word</A>, <A href="../Keywords/E.htm#equal">equal</A>, <A href="../Keywords/C.htm#ctype">ctype</A>, <A href="../Keywords/C.htm#character">character</A>, <A href="../Keywords/R.htm#reverse">reverse</A>
<div class="copy"></div>
</BODY></HTML>
